JBoss.orgCommunity Documentation

Mobicents SIP Presence Service User Guide


Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Provide feedback to the authors!
1. Introduction to the Mobicents SIP Presence Service
1.1. Architecture of the Mobicents SIP Presence Service
2. Installing the Mobicents SIP Presence Service
2.1. Mobicents SIP Presence Service: Installing, Configuring and Running
2.1.1. Pre-Install Requirements and Prerequisites
2.1.2. Downloading
2.1.3. Configuring (and Setting JBOSS_HOME)
2.1.4. Installing
2.1.5. Running
2.1.6. Stopping
2.1.7. Uninstalling
2.1.8. Building from Source Project
2.1.9. Binary Releases Daily Snapshots
3. Mobicents XML Document Management Server
3.1. Configuring the XDM Server
3.1.1. Configuring the XDM Server XCAP root
3.1.2. Other configurations in the XDM Server XCAP Interface
3.1.3. Configuring the XDM Server XCAP Diff SIP Subscription Interface
3.1.4. XDM Server User Profile Provisioning
3.1.5. XCAP Application Usages
4. Mobicents SIP Presence Server
4.1. Functional Architecture of the SIP Presence Server
4.2. Configuring The SIP Presence Server
4.2.1. Configuring the Abstract SIP Event Publication Interface
4.2.2. Configuring the Abstract SIP Event Subscription Interface
4.2.3. Configuring the Concrete SIP Event Interfaces
5. Mobicents Resource List Server
5.1. Disabling the Resource List Server
6. Client JAIN SLEE Applications
6.1. XDM Client JAIN SLEE Enabler
6.2. The Mobicents SIP Event Publication Client Enabler
6.2.1. Integrating the Mobicents SIP Event Publication Client Enabler
6.2.2. Using the Mobicents SIP Event Publication Client Enabler
6.3. The Mobicents SIP Event Subscription Client Enabler
6.3.1. Integrating the Mobicents SIP Event Subscription Client Enabler
6.3.2. Using the Mobicents SIP Event Subscription Client Enabler
6.4. The Mobicents Presence Client Enabler
6.4.1. Integrating the Mobicents Presence Client Enabler
6.4.2. Using the Mobicents Presence Client Enabler
6.5. Client Application Examples
7. Logging, Traces and Alarms
7.1. Log4j Logging Service
7.1.1. Simplified Global Log4j Configuration
7.2. Alarms
7.3. Trace Facility
7.3.1. JAIN SLEE Tracers and Log4j
A. Revision History
Index

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:

The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.

Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:

The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in Mono-spaced Bold. For example:

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.

Note the > shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select Mouse from the Preferences sub-menu in the System menu of the main menu bar' approach.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

Note the words in bold italics above username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: http://bugzilla.redhat.com/bugzilla/ against the product ${product.name}, or contact the authors.

When submitting a bug report, be sure to mention the manual's identifier:

If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

The Mobicents SIP Presence Service provides presence functionalities to SIP-based networks using standards developed by the Internet Engineering Task Force (IETF), the Open Mobile Alliance (OMA), the 3rd Generation Partnership Project (3GPP) and the European Telecommunications Standards Institute (ETSI).

The SIP Presence Service is comprised of three separate but interrelated servers.

A major advantage of the Mobicents SIP Presence Service is that, depending on your needs, each server can be deployed separately, or all servers can be integrated on the same host.

The Mobicents SIP Presence Service is built on top of Mobicents JAIN SLEE, a high performance and scalable Application Server and uses many additional Java Enterprise (JEE) technologies, such as Java Persistence API (JPA) to manage data.

In addition, there are JAIN SLEE internal client interfaces available for interaction with each server, which distinguishes the Mobicents SIP Presence Service from other presence services.

Resources and Further Information about the Mobicents SIP Presence Service

For further information on the Mobicents SIP Presence Service, here is a list of additional resources:

There are multiple binary distributions of the Mobicents SIP Presence Service.

The Mobicents Platform (Mobicents) is built on top of the JBoss Application Server (JBoss AS). You do not need to set the JBOSS_HOME environment variable to run any of the Mobicents Platform servers unless JBOSS_HOME is already set.

The best way to know for sure whether JBOSS_HOME was set previously or not is to perform a simple check which may save you time and frustration.

Checking to See If JBOSS_HOME is Set on Unix

At the command line, echo $JBOSS_HOME to see if it is currently defined in your environment:

~]$ echo $JBOSS_HOME

The Mobicents Platform and most Mobicents servers are built on top of the JBoss Application Server (JBoss AS). When the Mobicents Platform or Mobicents servers are built from source, then JBOSS_HOME must be set, because the Mobicents files are installed into (or “over top of” if you prefer) a clean JBoss AS installation, and the build process assumes that the location pointed to by the JBOSS_HOME environment variable at the time of building is the JBoss AS installation into which you want it to install the Mobicents files.

This guide does not detail building the Mobicents Platform or any Mobicents servers from source. It is nevertheless useful to understand the role played by JBoss AS and JBOSS_HOME in the Mobicents ecosystem.

The immediately-following section considers whether you need to set JBOSS_HOME at all and, if so, when. The subsequent sections detail how to set JBOSS_HOME on Unix and Windows

You DO NOT NEED to set JBOSS_HOME if...
You MUST set JBOSS_HOME if...

Naturally, if you installed the Mobicents Platform or one of the Mobicents server binary releases which do not bundle JBoss AS, yet requires it to run, then you should install JBoss AS before setting JBOSS_HOME or proceeding with anything else.

Setting the JBOSS_HOME Environment Variable on Unix

The JBOSS_HOME environment variable must point to the directory which contains all of the files for the Mobicents Platform or individual Mobicents server that you installed. As another hint, this topmost directory contains a bin subdirectory.

Setting JBOSS_HOME in your personal ~/.bashrc startup script carries the advantage of retaining effect over reboots. Each time you log in, the environment variable is sure to be set for you, as a user. On Unix, it is possible to set JBOSS_HOME as a system-wide environment variable, by defining it in /etc/bashrc, but this method is neither recommended nor detailed in these instructions.

Procedure 2.1. To Set JBOSS_HOME on Unix...

  1. Open the ~/.bashrc startup script, which is a hidden file in your home directory, in a text editor, and insert the following line on its own line while substituting for the actual install location on your system:

    export JBOSS_HOME="/home/<username>/<path>/<to>/<install_directory>"
  2. Save and close the .bashrc startup script.

  3. You should source the .bashrc script to force your change to take effect, so that JBOSS_HOME becomes set for the current session[1].

    ~]$ source ~/.bashrc
  4. Finally, ensure that JBOSS_HOME is set in the current session, and actually points to the correct location:

    Note

    The command line usage below is based upon a binary installation of the Mobicents Platform. In this sample output, JBOSS_HOME has been set correctly to the topmost_directory of the Mobicents installation. Note that if you are installing one of the standalone Mobicents servers (with JBoss AS bundled!), then JBOSS_HOME would point to the topmost_directory of your server installation.

    ~]$ echo $JBOSS_HOME
    /home/silas/
Setting the JBOSS_HOME Environment Variable on Windows

The JBOSS_HOME environment variable must point to the directory which contains all of the files for the Mobicents Platform or individual Mobicents server that you installed. As another hint, this topmost directory contains a bin subdirectory.

For information on how to set environment variables in recent versions of Windows, refer to http://support.microsoft.com/kb/931715.



[1] Note that any other terminals which were opened prior to your having altered .bashrc will need to source ~/.bashrc as well should they require access to JBOSS_HOME.

The Mobicents XML Document Management Server (XDM Server) is part of the Mobicents SIP Presence Service; it is the first free and open source implementation of an XML Document Management Server as defined in the Open Mobile Alliance (OMA) XML Document Management v1.1 specification. This functional element of next-generation IP communication networks is responsible for handling the management of user XML documents stored on the network side, such as presence authorization rules, contact and group lists (also known as resource lists), static presence information, and much more.

Important

The SIP interface partially implements the XCAP Diff Event IETF draft, version 3. Subscriptions to a single document or usage by an entire application are supported. However, these differing usages do not extend to the single-XML element or attribute value level. Regarding the notifications, the diff-processing subscription parameter, if present, is ignored, and patching of content is not available at the moment, which means that only the document etags, new and/or old, will be provided.

The XDM Server comprises the following functional elements:

What is an XCAP Application Usage?

"Each XCAP resource on a server is associated with an application. In order for an application to use those resources, application specific conventions must be specified. Those conventions include the XML schema that defines the structure and constraints of the data, well-known URIs to bootstrap access to the data, and so on. All of those application specific conventions are defined by the application usage." RFC 4825

Each XCAP Application Usage defines:

The Mobicents XDM Server XCAP Application Usages are implemented with a few simple Java classes and some meta data, it is very easy to develop additional ones.

Each Application Usage is represented by a Java class extending the abstract org.mobicents.xdm.server.appusage.AppUsage class:



package org.mobicents.xcap.server.slee.appusage.presrules;
// ...
public class PresRulesAppUsage extends AppUsage {
    public static final String ID = "pres-rules";
    public static final String DEFAULT_DOC_NAMESPACE = "urn:ietf:params:xml:ns:pres-rules";
    public static final String MIMETYPE = "application/auth-policy+xml";
    private static final String AUTH_ONLY_DOCUMENT_NAME = index;
    public PresRulesAppUsage(Validator schemaValidator) {
        super(ID,DEFAULT_DOC_NAMESPACE,MIMETYPE,schemaValidator,AUTH_ONLY_DOCUMENT_NAME);
    }
}
            

Methods for data constraints and resource interdependencies can be overriden:



public void checkConstraintsOnPut();
public void checkConstraintsOnDelete();
public void processResourceInterdependenciesOnPutDocument();
public void processResourceInterdependenciesOnDeleteElement();
//...
            

Multiple constructors exposed to provide your App Usage XML Schemas Validators and/or Authorization Policies:



public AppUsage(String auid, String defaultDocumentNamespace, String mimetype, 
    Validator schemaValidator, String authorizedUserDocumentName);
public AppUsage(String auid, String defaultDocumentNamespace, String mimetype, 
    Validator schemaValidator, AuthorizationPolicy authorizationPolicy);
public AppUsage(String auid, String defaultDocumentNamespace, String mimetype, 
    Validator schemaValidator, Validator uniquenessSchemaValidator, 
    String authorizedUserDocumentName);
public AppUsage(String auid, String defaultDocumentNamespace, String mimetype, 
    Validator schemaValidator, Validator uniquenessSchemaValidator,
    AuthorizationPolicy authorizationPolicy);
            

A deployer to load/unload the App Usage into the XDM Server, it should extend class named org.mobicents.xdm.server.appusage.AppUsageDeployer:



package org.mobicents.xcap.server.slee.appusage.presrules;
// ...
public class PresRulesAppUsageDeployer extends AppUsageDeployer {
    
    @Override
    public AppUsageFactory createAppUsageFactory(Schema schema) {
        return new PresRulesAppUsageFactory(schema);
    }
    @Override
    public String getSchemaRootNamespace() {
        return PresRulesAppUsage.DEFAULT_DOC_NAMESPACE;
    }
}
            

Multiple XML schema files may be combined, starting point is the namespace returned by getSchemaRootNamepsace(), which not always is the same as the app usage's default doc namespace.

The deployer is actually a JBoss Microcontainer Bean, and a jboss-beans.xml file is needed in the META-INF directory of the app usage jar:



<?xml version="1.0" encoding="UTF-8"?>

<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="urn:jboss:bean-deployer:2.0">
        
    <!-- Registers the APP USAGE DEPLOYER AS JBOSS MICROCONTAINER BEAN -->
    
    <bean name="Mobicents.XDMS.AppUsage.Deployer.PresRules" class="org.mobicents.xcap.server.slee.appusage.presrules.PresRulesAppUsageDeployer">           
      <!-- this app usage depends on app usage management only -->
      <depends>Mobicents.XDMS.AppUsageManagement</depends>      
   </bean>
   
</deployment>
            
            

A unique bean “name” is need, and of course the “class” name of the Deployer, nothing else needs to be changed.

The Mobicents SIP Presence Server is a free and open source implementation of a SIP Presence Server, as defined by the Internet Engineering Task Force (IETF), the Open Mobile Alliance (OMA), the 3rd Generation Partnership Project (3GPP) and the European Telecommunications Standards Institute (ETSI).

The SIP Presence Server is an entity that accepts, stores and distributes SIP presence information.

The SIP Presence Server is comprised of the following functional elements:

Presence Publication Control

This functional element manages the publication of presence events, which includes not only the handling of new publications, but also the refreshing, modification or removal of, already-published information.

Because the presence resource, which is also called a presentity, can have multiple publications simultaneously, such as some state published by a user agent or device, and some location data published by a Presence Network Agent (on behalf of the presentity), this element is also responsible for composing all of the different publications for the same resource.

In some presence networks, it may be of interest to allow resources to have a static presence state which is stored in the XDM Server. In cases like these, Presence Publication Control may need to interface with the XDM Server to retrieve and subscribe to (learn about changes to) that information, and use it when composing the final presence information document.

Presence Subscription Control

This functional element handles subscriptions to presence events or to the list of subscribers (watchers), for any specific resource. It is, of course, responsible for emitting notifications related to those subscriptions.

Presence authorization rules, which define if a subscription is allowed or rejected and, if allowed, define which transformations to the original presence events are needed, are stored on the XDM Server by the user. Thus, Presence Subscription Control needs to retrieve and subscribe to that information.

Presence Rules Cache

This element is responsible for interfacing with the XDM Server that manages the user's XML presence rules documents. It is responsible for providing the presence rules to the Presence Subscription Control, which are used to authorize the subscriptions it handles.

The implementation architecture of the SIP Presence Server also contains client-side components:

The Mobicents Resource List Server, or simply RLS, is the functional element which handles subscriptions to resources lists. A resource list is defined as a list of any kind of SIP presence entities, be it single presentities or other resource lists.

The RLS is specified by IETF RFC 5367. It is a XDM Client, which watches all RLS Services documents (each define a list of presence entities) stored in the related XDM Server, and processes SIP presence subscriptions to each RLS Service state, that is, the state for all presence entities deferred by from the service. When handling a subscription to a RLS Service, the RLS creates and manages (possibly virtual) subscriptions to each presence entity on the Presence Server, and notifies the subscriber for entity state change.

RLS Services are typically used to store the list of entities which the subscriber watch, and the list of entities which are allowed to subscribe its state.

Mobicents Resource List Server extends the Presence Server, it introduces an additional functional element, the RLS Services Cache. This element is responsible for managing the flat list of entities pointed by each RLS Service, and for that it subscribes changes in referred docs (RLS Services and related Resource Lists). Each time an RLS Service changes the cache notifies the related subscriptions, to ensure the subscriber is always subscribing the correct list of presence entities.

Important

The Mobicents RLS is currently limited to RLS Services stored in the integrated XDM Server, and such services should not refer other XDM Servers, otherwise the RLS will set the state for the related service as Bad Gateway.

The Mobicents SIP Presence Service is built on top of Mobicents JAIN SLEE, which means JAIN SLEE applications can be deployed and run in same JVM as the servers. Better yet, there are XDM and SIP Presence client enablers which can be integrated in such JAIN SLEE applications, allowing an easy interaction with the platform servers.

The Mobicents SIP Event Publication exposes a JAIN SLEE enabler for applications which want to interact as clients of a SIP Event Publication Server. The enabler does not uses SIP network protocols, thus providing better performance and less overhead to network communications.

The Enabler consists in an SBB which can be used in child relations, with a simple synchronous interface.

This chapter explains how to setup a JAIN SLEE Service Sbb to use the Enabler.

In short terms, a Service's Sbb will define the Enabler's Sbb as a child, and to achieve that it will need to setup the XML Descriptor, Abstract Class and SbbLocalObject interface.

In the last section we integrated the Enabler in the JAIN SLEE Service's Sbb, the Parent Sbb, in this section it is explained how to use the Enabler's Sbb, the Child Sbb.

The Mobicents SIP Event Publication Client Enabler Sbb, the Child Sbb, implements the org.mobicents.slee.sipevent.server.publication.PublicationClientControlSbbLocalObject, which extends the javax.slee.SbbLocalObject and org.mobicents.slee.sipevent.server.publication.PublicationClientControl interfaces, the latter declares the methods which can be used to interact with the PS and/or RLS:



package org.mobicents.slee.sipevent.server.publication;
public interface PublicationClientControl {
    public Result newPublication(String entity, String eventPackage,
            String document, String contentType, String contentSubType,
            int expires);
    public Result refreshPublication(String entity, String eventPackage,
            String eTag, int expires);
    public Result modifyPublication(String entity, String eventPackage,
            String eTag, String document, String contentType,
            String contentSubType, int expires);
    public int removePublication(String entity, String eventPackage, String eTag);
}
        
        

The Mobicents SIP Event Publication exposes a JAIN SLEE enabler for applications which want to interact as clients of a SIP Event Subscription Server, such as a PS or RLS. The enabler does not uses SIP network protocols, thus providing better performance and less overhead to network communications.

The Enabler consists in an SBB which can be used in child relations, with a simple asynchronous interface.

This chapter explains how to setup a JAIN SLEE Service Sbb to use the Enabler.

In short terms, a Service's Sbb will define the Enabler's Sbb as a child, and to achieve that it will need to setup the XML Descriptor, Abstract Class and SbbLocalObject interface.

The Mobicents SIP Event Subscription Client Enabler Sbb provides asynchronous callbacks to the Parent's Sbb, and that can only be achieved if the Parent's SbbLocalObject extends a specific Java interface, deployed also by the Enabler, and provides it's SbbLocalObject to the Enabler's Sbb, through a specific method exposed by the latter interface. The Enabler stores the Parent's SbbLocalObject and uses it when a callback to the Parent's Sbb is needed.

The SbbLocalObject which must be used or extended by the Parent's Sbb is named org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlParentSbbLocalObject, which extends the javax.slee.SbbLocalObject and org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlParent interfaces, the latter declares the callbacks which must be implemented in the Parent's Sbb Abstract Class:



package org.mobicents.slee.sipevent.server.subscription;
import org.mobicents.slee.sipevent.server.subscription.data.Subscription;
public interface SubscriptionClientControlParent {
    public void subscribeOk(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int expires,
            int responseCode);
    public void resubscribeOk(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int expires);
    public void unsubscribeOk(String subscriber, String notifier,
            String eventPackage, String subscriptionId);
    public void subscribeError(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int error);
    public void resubscribeError(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int error);
    public void unsubscribeError(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int error);
    public void notifyEvent(String subscriber, String notifier,
            String eventPackage, String subscriptionId,
            Subscription.Event terminationReason, Subscription.Status status,
            String content, String contentType, String contentSubtype);
    
}
        
        

The Parent's Sbb must define a reference to the Enabler's Child Sbb, declare which is the method name to get the related ChildRelation object, and also ensure the SbbLocalObject interface is defined correctly.

A reference to the Enabler's Child Sbb is defined right after the Parent's Sbb Vendor ID element, using the following XML element:



        <sbb-ref>
            <sbb-name>SubscriptionControlSbb</sbb-name>
            <sbb-vendor>org.mobicents</sbb-vendor>
            <sbb-version>1.0</sbb-version>
            <sbb-alias>sipEventSubscriptionClientChildSbb</sbb-alias>
        </sbb-ref>
        
        

The method name to get the Enabler's ChildRelation object must be defined after the CMP Fields (if any), this XML element links the sbb-alias previously defined with the abstract method declared in the Parent's Sbb Abstract Class:



        <get-child-relation-method>                 
            <sbb-alias-ref>sipEventSubscriptionClientChildSbb</sbb-alias-ref>
            <get-child-relation-method-name>getSIPEventSubscriptionClientChildRelation</get-child-relation-method-name>
            <default-priority>0</default-priority>
        </get-child-relation-method>
        
        

Finally, after the sbb-abstract-class element the Parent's SbbLocalObject interface name is defined:



        <sbb-local-interface>
            <sbb-local-interface-name>...</sbb-local-interface-name>
        </sbb-local-interface>
        
        

In the last section we integrated the Enabler in the JAIN SLEE Service's Sbb, the Parent Sbb, in this section it is explained how to use the Enabler's Sbb, the Child Sbb.

The Mobicents SIP Event Subscription Client Enabler Sbb, the Child Sbb, implements the org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlSbbLocalObject, which extends the javax.slee.SbbLocalObject and org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlSbbLocalObject interfaces, the latter declares the methods which can be used to interact with the SIP Event Subscription Server:



package org.mobicents.slee.sipevent.server.subscription;
public interface SubscriptionClientControl {
    public void setParentSbb(
            SubscriptionClientControlParentSbbLocalObject sbbLocalObject);
    public void subscribe(String subscriber, String subscriberdisplayName,
            String notifier, String eventPackage, String subscriptionId,
            int expires, String content, String contentType,
            String contentSubtype);
    public void resubscribe(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int expires);
    public void unsubscribe(String subscriber, String notifier,
            String eventPackage, String subscriptionId);
}
        
        

The Mobicents SIP Presence exposes a JAIN SLEE enabler for applications which want to interact as clients of the Presence (PS) or Resource List Server (RLS). The enabler does not uses SIP network protocols, thus providing better performance and less overhead to network communications.

The Enabler consists in an SBB which can be used in child relations, with a simple asynchronous interface.

This chapter explains how to setup a JAIN SLEE Service Sbb to use the Enabler.

In short terms, a Service's Sbb will define the Enabler's Sbb as a child, and to achieve that it will need to setup the XML Descriptor, Abstract Class and SbbLocalObject interface.

The Mobicents Presence Client Enabler Sbb provides asynchronous callbacks to the Parent's Sbb, and that can only be achieved if the Parent's SbbLocalObject extends a specific Java interface, deployed also by the Enabler, and provides it's SbbLocalObject to the Enabler's Sbb, through a specific method exposed by the latter interface. The Enabler stores the Parent's SbbLocalObject and uses it when a callback to the Parent's Sbb is needed.

The SbbLocalObject which must be used or extended by the Parent's Sbb is named org.mobicents.slee.sippresence.client.PresenceClientControlParentSbbLocalObject, which extends the javax.slee.SbbLocalObject and org.mobicents.slee.sippresence.client.PresenceClientControlParent interfaces, the latter declares the callbacks which must be implemented in the Parent's Sbb Abstract Class:



package org.mobicents.slee.sippresence.client;
import org.mobicents.slee.sipevent.server.subscription.data.Subscription;
public interface PresenceClientControlParent {
    public void newPublicationOk(Object requestId, String eTag, int expires);
    public void refreshPublicationOk(Object requestId, String eTag, int expires);
    public void modifyPublicationOk(Object requestId, String eTag, int expires);
    public void removePublicationOk(Object requestId);
    public void newPublicationError(Object requestId, int error);
    public void refreshPublicationError(Object requestId, int error);
    public void modifyPublicationError(Object requestId, int error);
    public void removePublicationError(Object requestId, int error);
    public void newSubscriptionOk(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int expires,
            int responseCode);
    public void refreshSubscriptionOk(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int expires);
    public void removeSubscriptionOk(String subscriber, String notifier,
            String eventPackage, String subscriptionId);
    public void newSubscriptionError(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int error);
    public void refreshSubscriptionError(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int error);
    public void removeSubscriptionError(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int error);
    public void notifyEvent(String subscriber, String notifier,
            String eventPackage, String subscriptionId,
            Subscription.Event terminationReason, Subscription.Status status,
            String content, String contentType, String contentSubtype);
}
        
        
The newPublicationOk(Object, String, int) method:

Callback from the Enabler indicating that the new publication request succeed.

The refreshPublicationOk(Object, String, int) method:

Callback from the Enabler indicating that the refresh publication request succeed.

The modifyPublicationOk(Object, String, int) method:

Callback from the Enabler indicating that the modify publication request succeed.

The removePublicationOk(Object) method:

Callback from the Enabler indicating that the remove publication request succeed.

The newPublicationError(Object, int) method:

Callback from the Enabler indicating that the new publication request failed.

The refreshPublicationError(Object, int) method:

Callback from the Enabler indicating that the refresh publication request failed.

The modifyPublicationError(Object, int) method:

Callback from the Enabler indicating that the modify publication request failed.

The removePublicationError(Object, int) method:

Callback from the Enabler indicating that the remove publication request failed.

The newSubscriptionOk(String, String, String, String, int, int) method:

Callback from the Enabler indicating that the new subscription request succeed.

The refreshSubscriptionOk(String, String, String, String, int) method:

Callback from the Enabler indicating that the refresh subscription request succeed.

The removeSubscriptionOk(String, String, String, String) method:

Callback from the Enabler indicating that the remove subscription request succeed.

The newSubscriptionError(String, String, String, String, int) method:

Callback from the Enabler indicating that the new subscription request failed.

The refreshSubscriptionError(String, String, String, String, int) method:

Callback from the Enabler indicating that the refresh subscription request failed.

The removeSubscriptionError(String, String, String, String, int) method:

Callback from the Enabler indicating that the remove subscription request failed.

The notifyEvent(String, String, String, String, Subscription.Event, Subscription.Status, String, String, String) method:

Callback from the Enabler notifying an event related with notifier state change.

The Parent's Sbb must define a reference to the Enabler's Child Sbb, declare which is the method name to get the related ChildRelation object, and also ensure the SbbLocalObject interface is defined correctly.

A reference to the Enabler's Child Sbb is defined right after the Parent's Sbb Vendor ID element, using the following XML element:



        <sbb-ref>
            <sbb-name>InternalPresenceClientControlSbb</sbb-name>
            <sbb-vendor>org.mobicents</sbb-vendor>
            <sbb-version>1.0</sbb-version>
            <sbb-alias>presenceClientChildSbb</sbb-alias>
        </sbb-ref>
        
        

The method name to get the Enabler's ChildRelation object must be defined after the CMP Fields (if any), this XML element links the sbb-alias previously defined with the abstract method declared in the Parent's Sbb Abstract Class:



        <get-child-relation-method>                 
            <sbb-alias-ref>presenceClientChildSbb</sbb-alias-ref>
            <get-child-relation-method-name>getPresenceClientChildRelation</get-child-relation-method-name>
            <default-priority>0</default-priority>
        </get-child-relation-method>
        
        

Finally, after the sbb-abstract-class element the Parent's SbbLocalObject interface name is defined:



        <sbb-local-interface>
            <sbb-local-interface-name>...</sbb-local-interface-name>
        </sbb-local-interface>
        
        

In the last section we integrated the Enabler in the JAIN SLEE Service's Sbb, the Parent Sbb, in this section it is explained how to use the Enabler's Sbb, the Child Sbb.

The Mobicents Presence Client Enabler Sbb, the Child Sbb, implements the org.mobicents.slee.sippresence.client.PresenceClientControlSbbLocalObject, which extends the javax.slee.SbbLocalObject and org.mobicents.slee.sippresence.client.PresenceClientControl interfaces, the latter declares the methods which can be used to interact with the PS and/or RLS:



package org.mobicents.slee.sippresence.client;
public interface PresenceClientControl {
    public void setParentSbb(PresenceClientControlParentSbbLocalObject parentSbb);
    public void newPublication(Object requestId, String entity,
            String document, String contentType, String contentSubType,
            int expires);
    public void refreshPublication(Object requestId, String entity,
            String eTag, int expires);
    public void modifyPublication(Object requestId, String entity, String eTag,
            String document, String contentType, String contentSubType,
            int expires);
    public void removePublication(Object requestId, String entity, String eTag);
    public void newSubscription(String subscriber,
            String subscriberdisplayName, String notifier, String eventPackage,
            String subscriptionId, int expires);
    public void refreshSubscription(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int expires);
    public void removeSubscription(String subscriber, String notifier,
            String eventPackage, String subscriptionId);
}
        
        
The setParentSbb(PresenceClientControlParentSbbLocalObject) method:

Passes the Parent's SbbLocalObject, which will be used by the Child Sbb to provide async results. If not invoked after the child creation the Enabler won't be able to callback the Parent Sbb.

The newPublication(Object, String, String, String, String, int) method:

Requests a new publication, for the specified Entity. The object argument is an ID that identifies the publication, and which will be provided in the response callback.

The refreshPublication(Object, String, String, int) method:

Requests a publication refresh, for the specified Entity and ETag. The object argument is an ID that identifies the publication, and which will be provided in the response callback.

The modifyPublication(Object, String, String, String, String, String, int) method:

Requests a publication modification, for the specified Entity and ETag. The object argument is an ID that identifies the publication, and which will be provided in the response callback.

The removePublicationOk(Object, String, String) method:

Requests a publication removal, for the specified Entity and ETag. The object argument is an ID that identifies the publication, and which will be provided in the response callback.

The newSubscription(String, String, String, String, String, int) method:

Requests a new subscription.

The refreshSubscription(String, String, String, String, int) method:

Requests a subscription refresh.

The removeSubscription(String, String, String, String) method:

Requests a subscription removal.

The Child Relation in the Parent Sbb Abstract Class is used to create and retrieve the Child Sbb, it is important to not forget to pass the Parent's SbbLocalObject to the Child after creation:



    public PresenceClientControlSbbLocalObject getPresenceClientChildSbb() {
        final ChildRelation childRelation = getPresenceClientChildRelation();
        if (childRelation.isEmpty()) {
            try {
                // creates new instance
                PresenceClientControlSbbLocalObject sbb = (PresenceClientControlSbbLocalObject) childRelation.create();
                // passes the parent sbb local object to the child
                sbb.setParentSbb((PresenceClientControlSbbLocalObject) sbbContext.getSbbLocalObject());
                return sbb;
            } catch (Exception e) {
                tracer.severe("Failed to create child sbb", e);
                return null;
            }
        }
        else {
            // reuse the existent one
            return (PresenceClientControlSbbLocalObject) childRelation.iterator().next();
        }
    }
        
        

The SbbLocalObject of the Child could also be stored in a CMP Field for the simplest retrieval, but unless you are going to reuse each instance several times it's better to have less state, specially in clustered environments.

In Mobicents SIP Presence Apache log4j is used for logging. If you are not familiar with the log4j package and would like to use it in your applications, you can read more about it at the Jakarta web site.

Logging is controlled from a central conf/jboss-log4j.xml file, in each server configuration profile. This file defines a set of appenders specifying the log files, what categories of messages should go there, the message format and the level of filtering. By default, in produces output to both the console and a log file (log/server.log).

There are 6 basic log levels used: TRACE, DEBUG, INFO, WARN, ERROR and FATAL.

Logging is organized in categories and appenders. Appenders control destination of log entries. Different appenders differ in configuration, however each supports threshold. Threshold filters log entries based on their level. Threshold set to WARN will allow log entry to pass into appender if its level is WARN, ERROR or FATAL, other entries will be discarded. For more details on appender configuration please refer to its documentation or java doc.

The logging threshold on the console is INFO, by default. In contrast, there is no threshold set for the server.log file, so all generated logging messages are logged there.

Categories control level for loggers and its children, for details please refer to log4j manual.

By default Mobicents SIP Presence inherits level of INFO from root logger. To make platform add more detailed logs, file conf/jboss-log4j.xml has to be altered. Explicit category definition for Mobicents SIP Presence looks like:



<category name="org.mobicents.slee"> 
    <priority value="INFO"/> 
</category>
        

This limits the level of logging to INFO for all Mobicents SIP Presence classes. It is possible to declare more categories with different level, to provide logs with greater detail.

For instance, to provide detailed information on Mobicents SIP Presence transaction engine in separate log file(txmanager.log), file conf/jboss-log4j.xml should contain entries as follows:



<appender name="TXMANAGER" class="org.jboss.logging.appender.RollingFileAppender"> 
    <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/> 
    <param name="File" value="${jboss.server.home.dir}/log/txmanager.log"/> 
    <param name="Append" value="false"/> 
    <param name="MaxFileSize" value="500KB"/> 
    <param name="MaxBackupIndex" value="1"/> 
 
    <layout class="org.apache.log4j.PatternLayout"> 
        <param name="ConversionPattern" value="%d %-5p [%c] %m%n"/> 
    </layout> 
</appender> 
 
<category name="org.mobicents.slee.runtime.transaction"> 
    <priority value="DEBUG" /> 
    <appender-ref ref="TXMANAGER"/> 
</category>
        

This creates a new file appender and specifies that it should be used by the logger (or category) for the package org.mobicents.slee.runtime.transaction.

The file appender is set up to produce a new log file every day rather than producing a new one every time you restart the server or writing to a single file indefinitely. The current log file is txmanager.log. Older files have the date they were written added to their filenames.

Besides manual logging configuration, described previously, Mobicents SIP Presence also exposes management operations that greatly simplify such configuration, allowing the administrator to select through predefined and complete logging configuration presets. Such operations are available in MBean named org.mobicents.slee%3Aservice%3DMobicentsManagement, and the available presets are:

The available management operations are:

Custom presets can be easily deployed in the application server too. Simply name the configuration file as jboss-log4j.xml.PRESET_NAME, where PRESET_NAME should be unique preset name, and copy it to directory $JBOSS_HOME/server/profile_name/deploy/mobicents-slee/log4j-templates, where profile_name is the server profile name.

Notification sources such as SBBs, Resource Adaptors, Profiles, and SLEE internal components use the JAIN SLEE Trace Facility to generate trace messages intended for consumption by external management clients. Management clients register to receive trace messages generated by the Trace Facility through the external management interface (MBean). Filters can be applied, in a similar way as in case of Alarms.

Within the SLEE, notification sources use a tracer to emit trace messages. A tracer is a named entity. Tracer names are case-sensitive and follow the Java hierarchical naming conventions. A tracer is considered to be an ancestor of another tracer if its name followed by a dot is a prefix of the descendant tracer’s name. A tracer is considered to be a parent of a tracer if there are no ancestors between itself and the descendant tracer. For example, the tracer named com is the parent tracer of the tracer named com.foo and an ancestor of the tracer named com.foo.bar.

All tracers are implicitly associated with a notification source, which identifies the object in the SLEE that is emitting the trace message and is included in trace notifications generated by the Trace MBean on behalf of the tracer. For instance, an SBB notification source is composed by the SBB id and the Service id.

For further information on how to use JAIN SLEE Trace Facility and receive JMX notifications refer to the JAIN SLEE 1.1 Specification.

Revision History
Revision 3.1Fri Dec 11 2009Eduardo Martins
Migration to Mobicents JAIN SLEE 2.x introduces major refactoring, specially on configurations.
Revision 3.0Fri Jul 10 2009Eduardo Martins
Major update to include XDM Server authentication and authorization, creation of XCAP Application Usages, SIP Client configuration examples and Resource List Server.
Revision 2.0Fri Mar 06 2009Douglas Silas
First release of the "parameterized" and much-improved Mobicents documentation.
Revision 1.0Tue Jan 20 2009Douglas Silas
Creation of the Mobicents SIP Presence User Guide separate from the Mobicents Platform User Guide.